р 


ae 


TREE-FORTH 
by TREE SYSTEMS 


Copyright (c) 1983 by TREE SYSTEMS 


USERS MANUAL 


Tree Systems 

Suite 233 

3645 28th St. S-E. 

Grand Rapids, Mi. 
49508 


po 


с” 


ro 


TABLE OF CONTENTS 
CHAPTER 1 
INTRODUCTION TO TREE-FORTH 


CHAPTER 2 - 

INSTALLATION AND SYSTEM DESCRIPTION 
2.1 Installing the circuit board 

2.2 Initial power-up 

2.3 Warm and Cold restart 

2.4 System response and errors 

2.5 Switching between TREE-FORTH 

and BASIC 


CHAPTER 3 
VISUAL EDITOR 
3.1 Editor Commands 
3.2 Compilation of code 
3.3 Creating Screens 
3.4 SLOW, FAST, and AUTO 


CHAPTER 4 
MASS STORAGE AND RETRIEVAL 
4.1 Information Storage 
4.2 Information Retrieval 
4.3 Compiling screens with loading 
4.4 Loading sequential screens 


CHAPTER 5 
DESCRIPTION OF STRUCTURE AND COMMAND FORMAT 
5.1 Stack structure 
5.2 Dictionary and its use 
5.3 Command Format 


CHAPTER 6 
MATHEMATICAL COMMANDS 


CHAPTER 7 
LOGICAL OPERATORS AND COMPARISON COMMANDS 
7.1 Logical Operators 
7.2 Comparison Operators 


CHAPTER 8 

NUMBER BASES AND STACK MANIPULATION 
8.1 Number Bases 
8.2 Stack Manipulation 


CHAPTER 9 
MEMORY COMMANDS AND MEMORY MANIPULATION 


page 
4 


44 
44 


іе 


рад . 


CHAPTER 18 
DATA TYPES AND VARIABLES 
19.1 Data Tpyes 
18.2 VARIABLE 
19.3 INTEGER 


CHAPTER 11 
CONTROL STRUCTURES 
11.1 IP ... BLSE сеен THEN 
11.2 IF ... THEN 
ilo. DO! Perea? БООР 
11.4... DO a. LOOP 
11.5 CASE STATEMENT 
11.6 BEGIN ... AGAIN 
11.7 BEGIN +... UNTIL 
11.8 BEGIN ... WHILE ... REPEAT 


CHAPTER 12 
CHARACTER INPUT/OUTPUT 
12.1 Description of Character Stack 
12.2 Character commands 
12.3 Character/number stack 


CHAPTER 13 
DEFINING WORDS 
13.1 COLON / SEMI-COLON Descriptors 
13.2 <BUILDS ... DOES> 


CHAPTER 14 
TASKING 


CHAPTER 15 
CODE COMPILER 


CHAPTER 16 
APPLICATIONS 


APPENDIX A ASCII CHARACTERS 
APPENDIX B ERROR CODES 


INDEX 


81 


84 


88 
91 


94 


Lor 


CHAPTER 1 


INTRODUCTION 


TREE SYSTEMS has prepared this document 
as a guide to the use of any word in 
TREE-FORTH. This manual is not meant to 
be a tutorial for learning FORTH. We 
recommend the book Starting FORTH by Leo 
Brodie which is published by Princeton- 
Hall books. 
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WHAT IS FORTH ? 


FORTH is a computer language, as is BASIC. It was 
first developed by Charles H. Moore in the late sixties. The 
language was conceptualized as a user friendly, high level 
computer language. The first element of FORTH to appear was 
the text interpreter at STANFORD in the early 19605. This 
version shows the process of executing a section of prog- 
ram attached to a defining word. 


Moore implemented the first version of FORTH on the 
IBM 1138 computer in the late 19605. The name FORTH, itself, is 
an abbreviation for fourth, to denote a fourth generation compu- 
ter language. The spelling was changed because the IBM 1130 
accepted only five-letter identifiers. A more complex version of 
FORTH appeared in 1972 after Moore developed a "Radio-Telescope 
Data Acquisition Program" at the National Radio Astronomy Obser- 
vatory (NROA). Finally, in 1973, FORTH Inc. was formed by Moore 
and was made available to the public. Soon a host of companies 
were selling FORTH for a variety of microprocessors. FORTH is 
now available for the Apple II, Heath WH-89, IBM PC, TRS 88, PDP- 
11, 151-11, and for systems using the 8080, 8086, 6800, 1802, 
6502, and 280 microprocessors. 


Moore also established the FORTH INTEREST GROUP. Through 
this group the fig-FORTH standard was developed. Where possible, 
TREE SYSTEMS has insured that TREE-FORTH matches the fig- 
FORTH standards. TREE SYSTEMS was not able to include all of the 
fig-FORTH commands due to lack of memory space. Also, TREE- 
FORTH includes some non-standard commands so that multi-tasking 
can be accomplished. 


TREE-FORTH is multi-tasking. This gives the programmer the 
ability to write real-time routines. This is described in chapter 
14. | 


TREE SYSTEMS believes that it has improved on the fig-FORTH 
standard by making TREE-FORTH a compiler directive language in- 
stead of interpretive.  Interpretive FORTH contains a series of 
addresses for each command ( or word ).. These addresses are 
stepped through by an inner interpreter which requires approx- 
imately 78 bytes of code. The inner inrepreter requires 170 T 
states of execution time (750 usec). This inner interpreter is a 
routine which must run as overhead for every address interpreted. 
A compiler directive language contains a series of calls to 
subroutines in. each command or word. Therefore, the overhead of 
an inner interpreter is not neccessary. The result is that 
compiler directive FORTH is quicker than interpretive FORTH in 
most programming applications, 


Since TREE-FORTH is not an interpretive language, but in- 
stead is a comiler directive language, it should not really be 
classified as a TIL (Threaded Interpretive Language). Instead it 
would be better to call the language a Threaded Compiler Language. 


WHAT IS TREE-FORTH ? 
TREE-FORTH contains most of the standard FORTH com- 
mands. The language of FORTH is a structured programming lan- 
| guage which allows the user to manage and manipulate all of the 
dynamic memory addressable by the microprocessor. FORTH is also 
a language in which the user can link down to machine code rou- 
tines. In this respect, FORTH is only a step above assembly 
level programming. However, FORTH is a high-level user friendly 
language in that it allows the user to create his own command 
Set. The entire program set written in FORTH is a customized set 
of instructions. In this way, FORTH approches other high level 
languages like LISP. 
In addition to the standard attributes of the FORTH lan- 
guage, TREE-FORTH adds a dimension to flexibility with multi- 
tasking.  Multi-tasking allows the user to schedule programs to 
run at any time in the future. This is a feature available only 
on much more expensive systems. With the proper hardware sup- 
port, a multi-tasking system can be used as a real-time control- 
ler. This means that the computer can operate at a speed suf- 
ficient enough to control the environment as events occur. A 
| multi-tasking system can also be used to enter data from a real- 
| time environment. An example would be sampling the breathing 
Cycle of a patient in the hospital in order to determine his or 
her respiratory rate. A multi-tasking System also gives the user 

! the flexibility of allowing а program to run іп the background ( 
example : a program which would take 5 minutes to run while 
editing a program in the editor system ). 


FORTH is somewhat harder to learn than BASIC. However, the 


flexibilty gained with FORTH makes it extremely desirable as a 
programming language. 
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| * * 
Е A TECHNICAL DESCRIPTION: ОЕ FORTH FOLLOWS. * 
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TREE-FORTH makes the Sinclair ZX81 or TIMEX Sinclair 1000 
a single user multi-tasking system. 


Example : 
TASK taskname programname 
IN 20 TM taskname EVERY 1 TS taskname 
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28 minutes after entering these lines, the program, 


programname, 


thereafter, 


will execute and continue executing every 1 second 
10 tasks пау be scheduled to run simultaneously. 


Program programname could read, for instance, a  tempera- 
ture and display it on the screen. 


TASKING INFORMATION: 
-Event Scheduling: 


* 
* 


Schedule with AT, IN, EVERY commands 
Task at 1/60 th of a second (maximum resolution) 


-Task Options: 


* 
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LOCK, UNLOCK, START, STOP, RUN 

Taskscan dynamically reschedule themselves. 
Up to 18 tasks can be scheduled at a time. 
Tasks can belinked to runinthe background. 
Each task has its own 32 bit clock. 

Tasks await execution in 63 deep event que. 


-Unique Editor: 


* 


+ *0X* 0 + + + XX 0 + 


User defined split screens 

Visual editor with blinking cursor 

Run editorwhile execution screen is running program 

Cursor Oriented у 

Delete lines or Characters 

Store line in pad. 

Insert lines from pad to editor screen. 

Automatic Character insert. 

Compile any line in the editor screen. 

Compile the entire screen. | 

Cassette I/O (INPUT/OUTPUT) routines use the editor 
screen for reading information or loading information. 


Information: 

TREE-FORTH uses all ASCII characters 

Extremely Fast. Run 30000 0 DO LOOP іп 1 second. 

High Priority Clock runs constantly for detection of 
stack underflow. 

Has a 16 bit number stack and an 8 bit character stack 
separate from the processor stack. 


NOTE : YOUR SYSTEM MUST HAVE 2 KB OF RAM 
IN ORDER TO RUN: TREE-FORTH. ANY MEMORY 
PACK WILL PROVIDE ENOUGH MEMORY. ALSO, 
IT IS POSSIBLE TO CONVERT THE 1KB VER- 
SIONS OF THE COMPUTER TO 2 KB, BY 
INSERTING A 2 KB MEMORY CHIP. 


FORTH IS RESIDENT IN AN 8 K EPROM HOUSED 
ON A CIRCUIT BOARD WITHIN THE 7Х81. ONE 
CAN SWITCH BETWEEN FORTH AND BASIC USING 
THE CHANNEL SWITCH ON THE BOTTOM OF THE 
COMPUTER, OR AN EXTERNAL SWITCH. 
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TREE-FORTH is based on an EPROM. The 
information on the chip can be erased by 
prolonged exposure to ultra-violet 
light. Therefore, TREE SYSTEMS can 
reburn any existing chip to update it to 
anew version. As the latest versions 
of the language becomes available TREE 
SYSTEM will burn any changes into 
existing chips for a fee of $6.00. 


Also, for a development fee TREE SYSTEMS 
can add any customized words to the 
EPROM. 


For further questions or requests, please mail correspondence to 


TREE SYSTEMS 

SUITE 233 

3645 28th ST. 

GRAND RPAIDS, MI 49598 
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CHAPTER 2 


INSTALLATION 
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2.1 SET-UP : 


TREE SYSTEMS sells TREE-FORTH for the 7Х81 / TS 1999 
already installed in a Sinclair computer, or as an extension to 
units already purchased. 


If you have an EPROM extension you will have to follow the 
following instructions to Set-up your FORTH system. 


STEP 1: Take the cover off the Computer. There are 5 
Screws in the bottom of the case. ( Three are under the pads. 
The pads are attached with adhesive and are easily removed. ) 

The case is shown in figure 2.1. 


After removing the Screws, the two halves of the case are 
easily separated. Opening the case will reveal the under side of 
the printed circuit board. Remove the two Screws in this board. 
This is shown in figure 2.2. Next, flip the circuit board over, 
making sure that the ribbon cable to the keyboard does not pull 
out. 


At thispoint, you should be looking at the various integ- 
rated circuits on the board. Identify the BASIC ROM chip.You can 
find a picture of the circuit board in your BASIC manual. In the 
SINCLAIR book the picture is on page 119. Іп the TIMEX book it 
is on page 121. 


Remove the BASIC ROM chip by prying up one side with a 
butter knife or another flat device. Be careful not to bend or 
touch any of the pins -- the chips are easily damaged by static 
electricity. The socket is shown in figure 2.3. 


STEP 2 : 


Remove the TREE-FORTH circuit board from the aluminum foil 
and styrofoam, being careful not to touch the pins. 


It is recommended that before you include your BASIC ROM on 
the TREE-SYSTEMS circuit board, insert the FORTH circuit without 
BASIC. In this way you can test the TREE-FORTH System. Insert 
the circuit board as shown in figure 2.4. There will be a group 
of resistors which will interfere with the FORTH board. Bend 
these over, making sure that there are no metal to metal con- 
tacts. (Bent resistors are shown in figure 2.3) 


Next, turn the SINCLAIR circuit board over and secure it 
with two screws you removed previously. Then, replace the cover 
and insert the 5 screws previously removed from the holes in 
the cover. At this point TREE-FORTH will be operational ( note 
that no BASIC will be available in this configuration ). 
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THE CASE 


FIGURE 2.1 


CIRCUIT BOARD SCREWS 


FIGURE 2,2 
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THE SOCKET AND BENT RESISTORS 


FIGURE Le 


INSERTING THE CIRCUIT BOARD 


FIGURE 2,4 
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2.2 INITIAL POWER-UP: 


After completing step two of the assembly, the system is 
ready for power-up. This section will describe for you how the 
Various screens in TREE-FORTH should look when you first turn the 
power on. 


After inserting the power line on the computer, the screen 
should look like Figure 2.5, 


If the screen did not come up, insert the power line again. 
You can also try a cold restart. This is accomplished by holding 
the SHIFT key and SPACE key down simultaneously for about a half 
second. | 


TREE SYSTEMS checks all the circuits before they are shipped 
to insure proper operation. It is possible that damage occurred 
during shipping. 

Here are some possible reasons why your screen did not come 
up properly : 


- Did you correctly insert the TREE SYSTEMS circuit board 


into the ROM socket ? The pins fit tightly, so do 
not be afraid to push very hard. 


- Did you bend any of the circuit board Pins over 
during installation ? 


- Did you put the circuit board pins in the correct 
holes in the socket ? Some sockets are 28 pin 
sockets. The holes 1,2,27, and 28 should remain 
open. 


- When you bent over the resistors, did you make sure 
that none of the wire leads where touching ? 


- Is your RAM pack attached properly ? If the connec- 
tions are not good, the system will not display the 
video information. It. is best to leave the 
RAM pack off ( if you have a 2 KB System ). Remove 
the pack and then, try to power-up again by removing 
the power line and reinserting it. 


If there are further problems than the ones mentioned 
above, you may call TREE SYSTEMS and we will try to 
help you trouble shoot your installation over the 
phone. Call : 1-616-949-8506. 
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FIGURE 245 


There are 
we have seen. 
split screen, 
Now the screen 


two sets of screens in TREE-FORTH. The first one 
The second one is a split screen. To display the 
hold down the SHIFT and EDIT keys simultaneously. 
should appear as shown in Figure 2.6. 


This is the editor portion 
of the screen. It is referred 
to as ED in software 


HHRPPR PEPER TREES REESE ES ERRRRS ESSERE ESS 


This is the run time portion of 
the screen. It is referred to 
as CO or console in software 


EDITOR SCREEN 
FIGURE: 2.6 


You can toggle between the two portions of the split screens 
by depressing the SHIFT and EDIT keys. 


To insure that your system is running properly, type the 
following in the execution portion of the screen. 


VLIST (ENTER) | 
This will display all of the 


TREE-FORTH words presently 
in memory. 
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Also, enter : 


«CPU (ENTER) This indentifies the Processor 
which is presently running. 


2.3 WARM AND COLD RESTART 
The TREE-FORTH can be re-initialized from 
software anytime without having to pull out the 
power supply line. 
А. WARM RESTART 2 


WARM (ENTER) will execute a warm restart. 


A warm restart can also be accomplished 
by holding BREAK (SHIFT/SPACE) down for an in- 
stant. 


A warm restart resets the Stack pointers to the 
absolute bottom. The System checks for a catastrophic 
error, such as overwriting the system variables. If 
necessary, a warm restart calls a cold restart to 
recover. The editor is reset to the CONSOLE screen. 
Finally, if the task flag is OFF ( command TOFF ) any 
background task is set to a null program and all tasks 


are LOCKED. 


B. COLD RESTART : 
Command : 


COLD (ENTER) 


A cold restart is accomplished by holding the BREAK 


key down for about a half second. | 


А cold restart reconfigures the entire 


system and brings up the orginal screen, as if the 
power were just turned on. Note that all dynamic memory 
( RAM > 4000 H ) is erased. Cold restart also checks 
for the amount of RAM attached to the Sinclair and sets 


this value in memory. 
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2.4 SYSTEM RESPONSE AND ERRORS 


TREE-FORTH prompts the user with an OK after each success- 
ful operation in the execution screen. The operation may be 
something as simple as putting a number on the stack, or as con- 
plicated as an entire line of program. As long as no error is 
found, the system reports with an ОҚ, 

If some error should appear during an operation, the ERROR 
Statement will be displayed on the screen followed by an error 
code. The error codes can be found in appendix в. 


2.5 SWITCHING BETWEEN TREE-FORTH AND BASIC. 


The circuit board supplied by TREE SYSTEMS can also be 
configured to allow the user to switch between BASIC and TREE- 
FORTH. If you wish to do this, follow the instructions below. 
However, this will require some soldering. 


STEP 1: 
Follow the same procedure as required for inserting the TREE- 


FORTH circuit board. In this case, remove the circuit board from 
its sdcket, 


STEP 2: Insert the BASIC ROM chip next to the FORTH chip 
as shown below in Figure 2.7. 


INSERTING THE BASIC ROM 


FIGURE 2,7 
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After properly inserting the BASIC ROM, solder the oins in, 


STEP 2 : 
There isa small jumper wire which is wired froma 
Socket in the board to the ground plane ( the large amount of 
interconnected silver on the board). Remove this wire by heating 
the solder and pulling the wire with a long-nosed pliers. 
Take a long piece of wire and put it into the samehole. 


FOR AN EXTERNAL SWITCH : 


Take the free end of the wire just attached to the circuit 
board, and attach it to one side of a Single Pole Single Throw 
(SPST) switch. The other Side of this switch should be wired to 
ground. You can use the ground plane on the TREE SYSTEMS circuit 
board or the ground plane on the T/S computer. 


FOR THE CHANNEL SELECTOR AS A SWITCH: 


You may also elect to use your channel switch as the 
switch for toggling between BASIC and FORTH. To do this, take 
the 
long wire from the Circuit board and attach it to the center 
post on the channel switch. This is shown in figure 2.8.  FORTH 
will be channel 3 and BASIC will be on channel 2. 

One note : You will have to tepower when you switch from 
FORTH to BASIC in order to reinitialize the BASIC System. 


EXTENSION MEMORY : 


You may also elect to put an extension EPROM or ROM in the 
BASIC ROM place, When floating point arithmetic becomes avail- 
able for TREE FORTH, it will be in the form of an extension EPROM. 
For information on floating point, contact TREE SYSTEMS and ask 
for the Technical Reference Manual. 


FIGURE 2.8 
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CHAPTER 3 


VISUAL EDITOR 
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THE ‚EDITOR 


TREE-FORTH for the Sinclair uses ASCII characters. ASCII 
stands for the "America Standard Code for Information 
Interchange", which is the industry standard. A complete listing 
of the ASCII code can be found in appendix A. This is a devia- 
tion from the Sinclair BASIC. It uses its own, non-standard, 
character set. Using ASCII makes the system much more flexible 
in terms of comunicating with existing computer systems ( most of 
which use ASCII to communicate - including modems and printers ). 


The visual editor is a screen editor, not a line editor. 
This gives the user a great deal of flexibility in writing FORTH 
programs, 


There are two screens in TREE-FORTH, so don't be confused. 
The first screen appears when you turn on the power. ( See Fig. 
2.5 ). The second screen is displayed with the SHIFT/EDIT set of 
keys. Once you are in the second screen ( FIG. 2.6 ) you can use 
the upper portion for editing. The lower portion is an execution 
screen ( This will also be called the console ). The two halves 
are separated by a black band called the video pad. You can 
switch between edit and execution screens using the SHIFT/EDIT 
keys. 


Jl THE FOLLOWING ARE EDITOR COMMANDS: 


NOTE: IF YOU HOLD ANY KEY DOWN FOR MORE THAN 1 
SECOND, THE DEPRESSED KEY WILL REPEAT. 


SHIFT / <- : THIS MOVES THE CURSOR ONE SPACE TO 
THE LEFT. 

SHIFT / y : THIS MOVES THE CURSOR ONE LINE DOWN. 

SHIFT / ^ : THIS MOVES THE CURSOR ONE LINE UP. 

SHIFT / -> : THIS MOVES THE CURSOR ONE SPACE TO 
THE RIGHT. 

SHIFT / 9 : INSERTS A LINE IN THE SLOT WHERE THE 


CURSOR IS PRESENTLY POSITIONED. 


SHIFT / 4 : DELETES THE LINE ON WHICH THE CURSOR 
IS POSITIONED. 


SHIFT / RUBOUT 2 DELETES THE CHARACTER AT THE 


CURSOR POSITION. 
(RUBOUT may be labled DELETE on some keyboards) 
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NOTE: ON THE EDITOR SCREEN, DEPRESSING THE ENTER 
KEY (NEW LINE on some models) MOVES THE CURSOR 
DOWN ONE LINE. IT DOES NOT COMPILE THE LINE. 


Also, continued typing on a line will provide 
immediate wrap around onto the next line should you type 
beyond the end of the screen. However, if you go back 
and insert characters in full lines, they will not wrap 
around, Instead the end characters will be lost off the 
right side of the screen. | ; 


NOTE THAT INSERTION MODE IS AUTOMATIC. TYPING A 
CHARACTERIN THE MIDDLE OF A LINE MOVES ALL THE 
CHARACTERS FOLLOWING THE CURSOR TO THE RIGHT. 


3t e e de de de 2 2 2 2 2 2 2 2 2 2 2 de de de Je de de de de de hkkk hkkk khkk ХХ 


* Тһе following commands deal * 
* with the video pad. ж 
ж The pad is the black band be- * 
* tween the editor portion and the * 
* * 
* * 


execution portion of the screen. 
LE 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 272 22222 2022 ren 


SHIFT / 3 : TAKES THE LINE ON WHICH THE CURSOR 
IS LOCATED AND PUTS IT IN THE PAD. 


SHIFT / 2 : TAKES THE CONTENTS OF THE PAD AND IN- 
SERTS THEM ON THE LINE OF THE CURSOR. 
IT THEN SCROLLS PRESENT AND FOLLOWING 
LINES DOWN. 


On the following page, all the keys on the Sinclair keyboard 
are defined according to their function in TREE-FORTH. 
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KEY SHIFTED KEY 


GRAPHICS 
DELETE 
"п 
ОЕ 
STEP 
<= 
<> 
>= 


ТЖ сш Ошо >ш Он с нд г қО о соз оул RUN A 


ENTER FUNCTION 


SHIFT SHIFT 
2 2 
X ; 
с ? 
V / 
B ж 
М < 
М > 
e | 4 
SPACE |: Special 


‘Character 


SHIFTED KEY FUNCTION 


Switches between screens 

Fetches a line from the video pad 
Puts a line in the pad | 
Deletes а line from the editor screen 
Moves cursor left 

Moves cursor down 

Moves cursor up 

Moves cursor right 

Inserts line on editor screen 

Deletes 1 character 

Compiles an editor screen line 

Stores command. Displayed as ! 

Fetchs command. Displayed as @ 
Character 
Character 
Character 
Character 
Character 
Character 


00 00 99 өе 00 өө oo 
sewn] rn 


Clears the present screen 
Character 
Character 
Character 
Character 
Character 
Character 
Character 
Character 
Home : Cursor to upper left corner 


Character : 2 
Character : ; 
Character : ? 
Character : / 
Character : * 
Character : < 
Character : > 
Character : 4 


WARM Restart 
If held for 1/2 second COLD restart 
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3.2 COMPILATION OF CODE. 


The following commands deal with the compilation of code 
from the editor screen. There are two ways to write code in 
TREE-FORTH. The first is to enter commands one by one in the 
console screen. ( The console screen is defined in chapter 2). 
The more desirable method of writing code is towritea series of 
words in the editor screen and then either compile the entire 
screen or compile the lines one by one. This allows you the 
freedom to go back and change things in the editor screen and 
recompile. 


The commands below deal with compiling code from the 
editor screen. 


SHIFT / 0: COMPILES THE LINE OF CODE ON WHICH THE 
CURSOR APPEARS ( The compiled line appears 
in the execution screen after this command. ) 


NOTE THAT A FORTH WORD MAY BE MORE THAN ONE LINE LONG. 
IN THIS CASE, YOU WILL HAVE TO PLACE THE CURSOR ON THE 
TOP LINE, COMPILE IT, AND THEN MOVE THE CURSOR TO 
COMPILE THE REST OF THE LINE.DO NOT WORRY ABOUT THE 
COMPILER: IT WILL WAIT UNTIL IT FINDS A SEMI-COLON (;) 
BEFORE IT ASSUMES THAT THE END OF A FORTH WORD IS 
REACHED. 


ТЕ the line is successfully complied, an OK will 
appear at the end of the line. If the line does not 
compile properly due to a programming error, then ERROR will be 
displayed followed by the appropriate code. The error codes are 
found in appendix в. 


CPL : COMPILES THE ENTIRE EDITOR SCREEN. 


Use this command after you have filled the entire 
editor screen and wish to compile all the Statements. This is 
also very useful for compiling screens after they have been down 
loaded from the cassette tape. z 


“NOTE 1 : You do not have to write all of your code in the editor 
screen and then compile it. You can compile FORTH code line by 
line in either SCREEN 1 ( FIG. 2.5 ) or in the execution 
portion of SCREEN 2 ( FIG. 2.6 ). Each word that you type while 
on the execution screen is compiled immediately. It is for this 
reason that using the editor to hold uncompiled code is 
desireable. You can make corrections to the middle of a program 
before it is to late to change it. 
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NOTE 2 : The editor screen can be turned off in order to make 
the present screen only an execution Screen. 


Command: EOFF : Turns the editor screen off. 
As an example : 
Enter : 


EOFF (ENTER) 


Now, by repeatedly pushing the ENTER, key you can scroll 
the editor screen off the top of the screen. The editor screen 
can be turned back on by typing SHIFT/EDIT keys simultaneously. 


3.3 CREATING SCREENS 


Any number of screens can be created using the SCREEN 
command. A screen is a portion of the video display in which 
characters can be placed. You can have as many screens as wished. 
They can be any rectangular size, ranging from 1 by 1 to as large 
as wished. If a screen is defined outside the bounds of the 
video display, the screen will be defined in RAM outside the 
bounds of ЕО@@ to 10000Н ( video RAM). Note: screens can also 
be overlapped. 


The definition of a screen is outlined below : 


a b c d SCREEN name 


a = column number of upper left hand 
cormer. 


b = row number of upper left hand 
corner. 


C = column number of lower right hand 
corner. 


d = row number of lower right hand 
corner. 


name = this can be any screen name 

desired by the user. 
Example : | 
0 0 15 15 SCREEN Sl (ENTER) 


a The above command will create a screen starting in row 
l and column 1 and continuing to column 16 and row 16. 


2 
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To display something on this screen, type : 


" HELLO THERE " (ENTER) 
OR 

Sl .W (ENTER) 
OK 


For extended examples see Chapter 15. 


SCREENS ARE DEFINED IN THE DICTIONARY. THEY CAN BE 
DISABLED BY FORGETTING THEM JUST AS YOU WOULD FORGET 
ANY FORTH WORD. | 


For the above example : 
FORGET 51 (ENTER) 


3.4 FAST, SLOW, AUTO 


TREE-FORTH still accepts the SLOW and FAST commands 
as does Sinclair's BASIC. In FAST mode, the video display is 
turned off until the CPU finishes processing the program. In 
SLOW mode, the video display always remains on. However, in SLOW 
mode, only 20 percent of the processing time is used to execute 
the program; the other 80 percent is necessary to update the 
display. 

The individual keywords no longer initiate the SLOW and 
FAST commands. Instead, you must type them in letter by letter. 

TREE FORTH also supports the command AUTO. AUTO will 
interrupt the video display if the processor requires more than 
1/4 second to execute a program. 


TREE FORTH has a revision for making any screen reverse 
video. The word REV must be placed before the screen the 
programmer wishes to be reverse video. 

Example : 


REV .С0 


This will make the console screen reverse 
video. 
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CHAPTER 4 


MASS | STORAGE 
AND RETRIEVAL 


% 


* 


NOTE : BOTH LOAD AND STORE WILL TEMPORARILY 
STOP VIDEO OUTPUT TO THE SCREEN. THE 


BECAUSE NO INTERRUPTS ARE ISSUED DURING THE 
CASSETTE ROUTINES, ALL TASKING IS 
SUSPENDED. 


4.1 STORAGE 


TREE FORTH allows for the storage of screens ог а series of 
Screens on magnetic cassette tape. Note that the whole editor 
Sereen will be saved; therefore, máke Sure that only the informa- 
tion wanted appears on that screen. 


STORAGE COMMAND : 


Storage takes Place from the editor screen. ( This is the 
portion of the video display above the black band as shown in 
figure 2.6). Each Screen is loaded with an identifying number. 

You should take care to remember which number a specific 
Screen is, so that ifa large number of Screens are stored on a 


Simplest case : 
Fill the editor Screen with any information which you 
desire. After you are finished, go to the execution Screen. 
(Accomplished by typing SHIFT/EDIT). 


Such a screen might look like : 


THIS SCREEN WILL BE AN EXAMPLE 
SHOWING HOW ONE MIGHT STORE 
INFORMATION ON TO THE TAPE. NOTE 


THAT THIS SCREEN DOES NOT HAVE 
TO BE A PROGRAM. 


АТ FD@@ HEX) . 
HRIHEEEHEEERELEEEEEEEE EE E ELA 1 1 ays 
10 STORE (ENTER) 


Next, load the screen with any information which you desire. 
You can even use the example above. Then, store the Screen on to 
the tape by typing the following as shown above : 


27 


104 STORE (ENTER) 


" REMEMBER THAT THERE IS ACTUALLY A 5 SECOND LEADER ON MOST 
CASSETTE TAPES WHICH CAN NOT BE TAPED OVER. THEREFORE, ADVANCE 
THE TAPE AT LEAST 10 SECONDS BEFORE STORING INFORMATION. 


What does store actually do ? Here is a description : 


STORE : takes a number off the user stack, in 
this case 19, and stores the editor 
Screen with the number as an identifier. 


Note that you can only store information from the editor 
Screen. You can not store information from the execution screen 
( also referred to as the console screen ). This should not be a 
problem, because for most large programs, you will be working in 
the editor screen. 


4.2 RETRIEVAL 


To retrieve information from the tape, the LOAD command is 
used. As an example, retrieve the same screen we just loaded in 
the above paragraphs. 


The command is : 
18 LOAD (ENTER) 


LOAD :This commands takes the number onthe 
user stack as the screen number to be 
loaded from the tape. The routine will 
continue to look for the screen until 
it is found, or until it is interrupted 
by hitting the space key. 


After typing 10 LOAD, rewind the tape so that screen 
10 will surely be found, and then press PLAY and wait for the 
computer to read the tape. When the screen is read from the 
tape, the editor area will contain the same information that it 
contained when it was loaded on the tape. 


Special Note: Typing 0 STORE will insure that the screen will be 
the first loaded, no matter what number is 
specified with LOAD. 


Typing 27 LOAD will load the first screen found on the 
tape, regardless of the screen number. Also, all subsequent 
screens ( after the first screen ) can also be loaded using the 


--> command described below. 
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INTERESTING INFORMATION : TREE-FORTH allows апу infor- 
mation on the editor screen to be stored and loaded. The con- 
tents of the screen do not have to be FORTH words or definitions. 
2Х81 BASIC does not allow this. Now with TREE FORTH, you have a 
way to store any information that you wish, letters etc. 


4.3 LOADING AND COMPILING SCREENS 
When loading any program from the tape to the editor 
screen, all the code on that screen can be compiled as soon as it 
is loaded. 
The command to turn on the automatic screen compiler is : 
CON 
The command to turn the automatic screen compiler off is : 
COFF 
Example : 


Create a simple program on the editor screen. Store it on 
the tape as screen 1. Now use the following commands,: 


CON 1 LOAD (ENTER) 


This will automatically compile the screen which has 
been loaded from the tape. 


NOTE : THE SCREEN COMPILER DEFAULTS TO OFF 
ON INTIAL POWER UP, OR ON A COLD 
RESTART. | 


4.4 SEQUENTIAL SCREEN ‘LOADING 


There may be many times when your FORTH program is longer 
than one screen. In this case, each screen must be loaded and 
compiled before the next screen can be loaded. The instructions 
for doing this are found below. 


^ 


IT IS IMPORTANT THAT YOU STORE YOUR SCREENS 
IN INCREASEING SEQUENTIAL ORDER, IF YOU WANT 
TO LOAD AND COMPILE THEM IN SEQUENCE. 
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To store screens on to the tape in sequential order, you may 
* use the following command: 


<-- * This command stores the present editor screen 
i with a screen number which is 1 larger than 
the last: screen stored. 


In order to load screens sequentially, the command is : 


--» : This symbol, when placed at the bottom of the 
editor screen and compiled, increments the 
screen count and loads the next screen by 
incrementing the screen count. 


WARNING : IF YOU ARE COMPILING EACH SCREEN 
AS IT IS LOADED SEQUENTIALLY, YOU 
MUST GIVE THE COMPILER ENOUGH 
TIME TO COMPILE EACH SCREEN. 


There are two ways to accomplish this : 


1. Stop the tape after each screen has been loaded and is 
compiling. When the computer is ready to load another screen 
( i.e. horizontal lines appear, ) restart the tape. 

2. If large blank spaces are left on the tape when you are 
saving sequential screens, there should be enough time to compile 
each screen before the next one is to be loaded. 


Either of these methods should insure that the next 


screen on tape will not be "played" before the computer is ready 
to receive it. 
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CHAPTER 5 


DESCRIPTION OF EURE AND 
COMMAND FORMA 
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5.1 STACK STRUCTURE 


FORTH is different from most other computer languages in that 
it uses a stack. A stack stores things in the order in which 
they were entered. Items can be removed with the last item 


first. Here is an example: 


Configure your system so that you are on SCREEN 1, or the 


execution portion of SCREEN 2. Enter three numbers. 


0 E 2 (ENTER) The stack looks 
like this : 


2 top 
l 
g bottom 


To display the top item on the stack, simply type: 
. (ENTER) 


This will remove 2 from the stack and display it. 


Typing 
. (ENTER) 
a second time will display the 1. 


All the mathematical operations are also performed on the 
Stack. To examine this, type the following: 


8 2 3 (ENTER) The stack looks like : 3 
2 
0 
Now type : 
* (ENTER) 


This command takes the top two entries off the stack, 
multiplies them, and puts the result back on the stack. The 


result is : 
| 6 


8 


ТЕ another multiplication were performed, then: 


* (ЕМТЕК) Result: 


32 


МЕ =ч 


All of the commands in TREE-FORTH use a stack. TREE-FORTH has 
a separate 8 bit character stack and a 16 bit number stack. You 
will be using the number stack most of the time, The character 
stack is described in more detail in the chapter on character 


input and output. 


NOTE: For those of you who are interested, both the character 
and number stacks are seperate from the Processor stack. The 
character and number stacks are resident in RAM. This allows you 
to do some really interesting things in software. The number 
stack pointer is contained in the ІҮ register of the 288 Micro- 
processor. The character stack pointer is located at address 
FC84 H. Because of the unique way the Sinclair's memory is 
mapped this address is accessible with а 2 KB memory ,16 KB 
memory, 32 KB, or 64 KB. 


5.2 DICTIONARY AND ITS USE 


After reading the above section you should have a feel for 
how the number stack works. TREE-FORTH words are stored in 
another place in memory, the dictionary. The dictionary grows up 
Егом 4000 Н. Every FORTH word is stored in memory with a header. 
The header contains the number of characters in the word plus the 
characters of the word itself. The number of characters plus the 
characters themselves are used to search the dictionary when a 
word is entered. 


The programmer can create new words in the dictionary using 
various compilers. These compilers are described in detail in 
the following chapters. 


Here is an example of how a new word would be defined using 
the COLON / SEMI-COLON compiler. 


To create a word'which takes the average of two numbers on 
the stack and displays the result, type : 


: AVG + 2 / . ; (ENTER) on the execution screen. 

: АУС + 2 / . 5; (SHIFT/E) on the editor screen 

The above program computes averages by adding the top two 
values on the stack and then pushing 2 on the stack and perform- 
ing a divide. The period (. ) then takes the top value off the 
stack and displays it. | 


The program AVG can Бе used to take the average of two 
numbers. Find the average of 86 and 46 by typing : 


Е 86 46 AVG (ENTER) 
66 OK - 


The answer 66 is displayed to the screen. 


VARIABLEs and INTEGERs can also be created in the dict- 
ionary. This is described in Chapter 19. 


5.3 COMMAND FORMAT 


Most of the descriptions of the TREE-FORTH commands will be 
of the following form. 


top --> stack stack <-- top 
before COMAND after 
execution execution 


Each command is described by an example. The state of the 
stack is shown before and after the command is executed. The 
commands are first described in a generic format and then an 
example of each one is given with actual numbers. 

What the variables mean : 
n 16 bit number ( nl,n2,n3,etc. ) 
а 32 bit number ( dl,d2,d3,etc. ) 
sometimes nlow and nhigh are used to describe 
how double numbers appear on the stack or in 
the dictionary. 
u = unsigned 16 bit number‘ 
addr = represents an address in memory 
byte 
character 
boolean flag (@=false, l-true) 


mao 
нии 


34 


CHAPTER 6 


MATHEMATICAL COMMANDS 
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TREE-FORTH uses integer arithmetic. For some this may 
be inconvenient at first. However, one of the comodities a 
computer has is speed. Oftentimes it is desired that operations 
be performed as quickly as possible, and in а 280 integer arith- 
metic is much faster than floating point arithmetic. If you need 
more accuracy in your values, the values can be scaled by a 
factor, for example 100. Scaling by 100, for instance, would 
allow you to include cents in calculations based in the dollar 
and cents system. 


Most 16 bit arithmetic is signed arithmetic in TREE- 
FORTH. However, most 32 bit, and all 64 bit arithmetic is un- 
signed. This may present a problem if you are not keeping track 
of the approximate magnitude of your calculations. 


Here is the difference between signed and unsigned 
arithmetic. Below is listed a chart showing the difference of 
signed and unsigned numbers. Both the BINARY and HEX formats of 
the bit patterns for 16 bit numbers are given. You can extend 
this for 32 and 64 bit numbers. 


NN C — À— — áÀ— Pn 


UNSIGNED BINARY HEX SIGNED 


65535 11111111111111111 FFFF ei 
65534 11111211111111114 FFFE -2 
32768 1809090000000000 8900 -32768 
32767 @111111111111111 7ЕЕЕ 32767 
@ @000000020000000@ 404044 g 
TABLE 6.1 


UNSIGNED, SIGNED, BINARY, AND HEX NUMBERS 
+ (ADDITION) : Adds the top two stack entries nl and n2 
| leaving the result on the stack. 


nl + n 
n2 


Example type : 
1 1 + . (ENTER) 
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- (SUBTRACTION) : Subtracts the top entry „ nl, from the 
second entry, n2, and leaves the result 
on the top of the stack. 


nl - п 
п2 


Ехатр1е : 
22-4; а (ENTER) 


*(MULTIPLICATION) : Multiplies the top two entries, nl and 
n2, and leaves the result on the stack. 


nl * п 
п2 
Ехатр1е : 


2 4 * . (ENTER) 
8 OK 


/ (DIVISION) : Divides the second stack entry „ n2, by the 
top stackentry, nl, and leaves the result 


on top. 
nl / п 
п2 
Ехатр1е : 
4 2 / +. (ENTER) 
2 OK 


1+ (ADD 1) : Adds one to the top entry , nl, and leaves result 
on the stack. 


nl 1+ n 
Example : 
2 1+ . (ENTER) 
3 ок 


1- (SUBTRACT 1) :Subtracts one from the top entry and leaves 
the result on the top. 


nl 1- n 
Example : 


1 1- . (ENTER) 
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2+ (ADD 2) : Adds two to the top entry , nl, andleaves 
the result on the stack. 


P 


nl 2+ n 
Example : 
1 2%. (ENTER) 
3 OK 
2- (SUBTRACT 2) : Subtracts two from the top stack 
entry. 
nl 2- n 


Example : 
3 2- . (ENTER) 
1 ОК 


2% (MULTIPLY BY 2) : This multiplies the top stack 
entry by two. 


nl 2* п 
Ехатр1е : 3 2% -; (ENTER) 
6 ОК 
2/ (DIVIDE BY 2) : This divides the top stack entry 
by 2. 
nl 027 n 
Example : 4 2/ . (ENTER) 


2 OK 


ABS (Absolute Value) : Leaves the absolute value of 
the top entry on the top of the stack. 


nl ABS n 


Example : -12 ABS e (ENTER) 
| 12 ок 


МАХ (Maximum) : Finds the largest of the top two 
stack entries and leaves it on the stack. 
nl MAX n 
n2 


Example : 9 4 МАХ . (ENTER) 
9 ок 


38 


MIN (Minimum) : Finds the smallest of the top twostack 
entries and leaves it on the stack. 


nl MIN n 
n2 


Example : 9 4 MIN . (ENTER) 
4 ОК 


MINUS (Uniary minus) : Changes the sign of the top stack 
entry. Сап be toggled indefinitly. 


nl - n 


Example : -1 MINUS . (ENTER) 
1 ОК 


+- (SWAP SIGN ) : Applies the sign of the top entry, 
nl, to the second entry, n2, and 
leaves the second entry, with the 
correct sign, on the stack. 


nl +1 n2 (signed) 
n2 


Example : 2 3- %- . (ENTER) 
-2 OK 


“MOD: Performs the division , n2/nl, and leaves the 16 


bit remainder on the stack. 


nl MOD n 
n2 


Example : 5 2 MOD . (ENTER) 
1 OK 


/MOD: Performs the division, n2/nl, andleaves the 
remainder nl on the top, and the quotient, n2, on 
the bottom of the stack. 


nl /MOD nl 


n2. n2 
Example : 5 2 /MOD . (ENTER) 
1 OK . (ENTER) 
2 Ок 
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*/MOD: Multiplies the second, n2, and third, пз, entries 
and divides by the first, nl, leaving the re- 
mainder on the top of the stack and the result 
below it. ( Signed arithmetic ). 


nl * /MOD nl 
n2 n2 
n3 


Example 3 3 2 %/М00 . (ENTER) 
1 ОК . (ENTER) 


M* : This multiplies two 16 bit numbers, nl and n2, 
and leaves a 32 bit result, d. 


nl M* d 
n2 


Example : 20000 20000 M* О. (ENTER) 
400000900 OK 


M/ 2 This divides a 32 bit number, d, by a 16 bit 
number, n, leaving a 16 bit remainder on the 
top» nl, and the quotient, n2, on the bottom. 


n M/ nl 
d n2 


Example : .400000000 290000 M/ . (ENTER) 
0 OK . (ENTER). 
20000 OK 


( The dot before the 400000000 signifies 
that it is a double number. The dot 
may appear any place in the number. ) 


MD* 


This multiplies two 32 bit numbers and the 
stack leaving a 64 bit result. ( The result 
can only be displayed in pieces ). 


di MD* dhigh 
d2 dlow 


MD/ : This divides a 64 bit number by a 32 bit 


number, dl, leaving a 32 bit remainder,dl, 
and a 32 bit result, d2. 


dl 
dlow MD/ dl 


dhigh а2 
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*/ 2 Multiplies the second entry, n2, and the third 
entry, n3, and divides by the first, nl, leaving 
the result on the stack. 


nl */ n 
n2- 
n3 
Example : 46 3 */ . (ENTER) 
8 OK 


D+ (32 bit add) : This is a double precision add which 
adds the top two 32 bit numbers 
found on the stack. 


al D+ al 
d2 


Example : 40004. 40004. 0+ D. (ENTER) 
80000 OK 


D*- (DOUBLE SIGN SWITCH) :  Assigns the sign of the first 
entry, dl, to the second entry, d2, leaving 
the second entry with the proper sign. 


dl D+- d 
d2 


Example : 50000. 30000.- D+- D. (ENTER) 
-50000 OK 


D- (DOUBLE PRECISION -) : Performs a double preci- 
sion subtration of the top entry from 
the second entry. 


di | De. > d 
d2 ` 


DABS (DOUBLE PRECISION ABS) : This operation takes 
the absolute value of the double precison 
number on the stack. 


d р ABS d 
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DMINUS (DOUBLE PRECISION -) : Changes the sign on a 
doubleprecision number. 


d DMINUS d 


Example : 40000. DMINUS D. (ENTER) 
-40000 OK ` 


0% ( UNSIGNED * ) : This multiplies the two unsigned 
t numbers found on the user stack, 
leaving an unsigned result. 


ul U* u 
u2 


Example : 6000 6 U* U. (ENTER) 
36000 OK 


UMOD ( UNSIGNED MOD ) : Thesecond entry, u2, is 
divided by the top number, ul, 
leaving the unsigned remainder. 


ul UMOD u 
u2 


/ U/MOD ( UNSIGNED /MOD ) : The second entry, u2, is 
divided by the top number, ul, 
leaving the remainder on the top 
of the stack and the quotient on 
the bottom. 


E ul U/MOD ul 
a -u2 u2 
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CHAPTER 7 


LOGICAL OPERATORS AND 
е COMPARISON COMMANDS 
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LOGICAL OPERATORS 
AND : Performs a bitwise AND of the 16 bit 
numbers on the stack. Example : 


5 60000101 (8 bit ex) 
7 040400111 

AND 
result: 5 0960608101 


OR : Performs а bitwise OR of the 16 bit 
numbers on the stack. Example : 


(8 bit ex.) 


ол 


OR 


result: 13 000041101 
( 13 = D in HEXADEIMAL ) 


XOR : Performs а bitwise exclusive-or of the 
16 bit numbers on the stack 


5 


вова 
7 299004 


@ 10 1 (8 bit ex.) 
0: 1.11 
XOR 


result: 2 20000010 


COMPARISON OPERATORS: 


< : If second stack entry is less than the 
first, the operation leaves a 1, other- 
wise a 6. 


ul < 1 
u2 
Example: 0 2 < , (ENTER) 
1 ОК 
> : If second stack entry is greater than 


the first, the operation leaves a l, 
otherwise a 9. > 


ul > Е 
12 
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д> 


2 < 


D< 


D> 


. 
e 


oe 


Tests whether the top stack entry is 
0. ТЕ it is, then operation leaves a 
1 on the stack, otherwise 9. 


ul g= Е 


Tests whether the stack entry is positive. 


If number is positive, operation leaves 
а 1, otherwise а 6. 


ul 9> Е 


Tests whether the stack entry is 
negative. If the number is negative 
а l is left on the stack, otherwise a @. 


ul @< £ 


Tests whether the top two stack entries 
are equivalent. If they are, the opera- 
tion leaves a 1, otherwise a 0. 


ul = £ 
u2 


Checks if the second 32 bit number is 
larger than the first 32 bit number. 

If the operation is true, then a 1 is 
left on the stack otherwise a 8 is left. 


dl D< Ё 
а2 
Checks if the second 32 bit number is 
larger than the first 32 bit number. 
I£ operation is true, then a l is 
left on the stack otherwise a 0 is left. 


al D> £ 
az” 


Checks if the two 32 bit numbers on the 

stack are equivalent. ТЕ they are, а 1 

is placed on the stack, otherwise a Y is 
left. 


al D= £ 
d2 
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DMAX : Leaves the larger of the two 32 bit numbers 
on the stack. 


al DMAX d 
d2 


DMIN: Leaves the smaller of the two 32 bit 
numbers on the stack. 


al DMIN d 
a2 


00= : Checks whether the 32 bit number on the 
Stack is equal to zero. If it is, a 1 is 
left on the stack, otherwise a zero. 


d DG= Е 
U< : This is an unsigned less-than comparison 
of the two 16 bit values on the top of 
the stack. If u2 < ul, then a 1 is left 


on the stack. Otherwise, a zero is left, 


ul U< É 
u2 
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CHAPTER 8 


NUMBER BASES 
and STACK MANIPULATION 
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8.1 Number bases : 


NOTE : ON INTIAL POWER UP, TREE-FORTH DEFAULTS 
TO DECIMAL ( BASE 14, 0 -9)), 


DECIMAL : Sets the decimal base ( all entries 
displayed in base 19 Nee 


НЕХ : Sets the base to hexadecimal, base 16 ( all 
entries displayed in base 16 Ys 


BASE : An INTEGER value used to modify 
the current base of the System. 


BASE base 
Note that any base is legal. 
CHANGING BASES : The base can be changed by 
Placing the desired base on 


the user stack and executing 
TO BASE , 


COMMANDS : 
3 TO BASE (ENTER) 
( changes the current base to 3 ) 
BASE . (ENTER) will print the base 


STACK MANIPULATION COMMANDS: 
8.2 STACK MANIPULATION: 
+ 2 А period prints the top number stack 
entry. 
3 
22 А 1 
1 
( 3 is displayed to the screen. ) 


D. : Double number display. A double number 
is taken off the stack and sent to the screen. 
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0. :Unsigned numberdisplay. An unsigned number 
is taken off the stack and displayed to the 
screen. 


0. : This puts a double number ( 32 bits ) on 
the stack. 


S-»D : This is a 16 to 32 bit sign extension. 
D->Q : This is a 32 to 64 bit sign extension. 


DROP : Drops the top number stack entry 


nl DROP n2 
n2 
2DROP : Drops the top two entries off the stack. 
nl 2DROP n3 
n2 
n3 


DUP : Duplicates the top number stack entry 


nl DUP nl 
nl 


?DUP : Duplicates the top entry only if it is 
non-zero. 


OVER : Copies the second entry on the stack 
to the top. 
nl OVER n2 
n2 nl 
2 п2 
РІСК : Copies the entry indexed by the top 
stack entry to the top. 
nl 2 PICK n2 
n2 nl 
n3 n2 
n3 


TYPICAL USAGE : 
STACK : 4 3 2 1 
COMMAND : 3 PICK 
STACK : 4 3 2 1 3 


( A 2 PICK is just like an over.) 
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SWAP : This command interchanges the top 
two stack entries. 


nl SWAP n2 
n2 nl 


DSWAP : This command exchanges the top two 
double (32 bit) numbers on the stack. 


dl DSWAP d2 
d2 dl 


ROT : This command rotates the top 3 entries. 
Entry 3 goes to the top of the’ stack. 
The top entry is moved to the 2nd 
entry. The 2nd entry goes to the 3rd 


entry. 
nl ROT n3 
n2 nl 
n3 n2 
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CHAPTER 9 
MEMORY COMMANDS 


and MEMORY MANIPULATION 


51 


ЕС56Н is an address containing the present memory 
size connected to the Sinclair. To display the memory 


| 


size 


type the following. 


HEX (ENTER) 


OK 
ЕС56 8 (ENTER) 

OK 
DECIMAL . (ENTER) 

2048 OK This is the memory size of 


a system with 2 KB of RAM. 


MEM : This is a command which puts the add- 
ress of the location containing the 
the current available memory left in 
RAM. 


Typical usage : 


DECIMAL MEM . (ENTER) 
648 OK 
this would be the amount of 
memory for a 2 KB system on 
power up. 


VLIST : This will display all the FORTH 
words presently found in memory. 


Usage: 
VLIST (ENTER) 


SP@ : This gives the current address of the 
stack pointer. 


ALLOT : This command reserves the amount of 
dictionary according to the value 
found on the stack. 


8 ALLOT g 
@ 


The above would leave 8 bytes of 
space in the dictionary. 


@ ( STEP on the Sinclair ) : This fetches the 


value at the memory location on the top of the 


stack. The value is placed on the stack. 


addr в nl 
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A TYPICAL SET OF COMMANDS WOULD BE : 


HEX (enter) 

FDOO а (enter) 

« (ENTER) This would display the number 
found at address FD90H. 


! ( OR on the Sinclair ) : Stores the second 
Stack entry in the memory location specified 
by the top entry. 


addr ! -- 
n 


A TYPICAL SET OF COMMANDS WOULD BE : 


HEX (enter) 
32 Е000 ! (enter) 
( This stores 32 in memory location Ерӣб H ) 


WARNING : TREE-FORTH will not shield you from 
storing values in dangerous areas ( for 
example the system variables ). So be 
careful to store only in free memory. 


? E Fetches and prints the contents of the 
address on the top of the stack. 


addr ? -- 


A TYPICAL COMMAND WOULD BE : 


HEX Е000 ? (ENTER) 
( Entering this statement after the. above 
Store.- ! - would display a 32 to the 
Screen ). 


+! 2 Increments the contents of memory having 
the address on the top of the stack by the 
second item on the stack. 


addr. == 
n +1 


A TYPICAL COMMAND WOULD BE : 
l Е000 +! (enter) 
( Entering this statement after the above 
store - ! - would change the contents of 
memory from 32 to 33 ). 
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св 


СОРҮ 


ЕВОЕ 


РАСЕ 


BLK 


*ORG 


4. 


° 
е 


: S 
t 
t 


tores a BYTE of information (8 bits) into 
he location specified by the address at 
he top of the stack. 


addr -- 
р С: 


Fetch опе BYTE of information ( 8 bits ) 


.. 


oe 


from the location described by the 
address on the top of the stack. 


addr са b 
This copies one screen of information 


to the address on the top of the stack 
from the address found as the second entry. 


addrl COPY --- 
addr2 


This puts the address of the frame 
buffer on the user stack. 


To change FBUF you must type : 
addr TO FBUF 


This puts the present page ( of the 
screen ) on the stack. You can change 


any page by typing : 
п TO PAGE 


This variable contains the address 

for the address to which the tape 
will down load. ( Default is ЕО0@ H). 
To change this value type : 


addr ТО BLK 


5 Adds the number found on the 


u 
b 


T 


St 
fo 


addr 
nlow 
nhig 


Ser stack to the address of the 
eginning of the system variables. 


he origin for TREE-FORTH is FC5@ H 


ores a 32 bit number at the address 
und at the top of the stack. 


D! -- 


h 
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Memory would look like : 


Da 


Р е 


с, 


HERE 


addr -> nlow 
addr+2 -> nhigh 


Fetches a 32 bit number found in the 
location whose address is on the top 
of the stack. 


addr ра nhigh 
nlow 


Stores the 16 bit number found on the 
number stack in the dictionary at the 
next available location. 


3456 , 9 
g 


This stores the 8 bits found at the 
specified address in the next available 


location in dictionary. 


addr 
5 C, g 
0 


This word places the address of the next 


free dictionary space on to the stack. 


-- НЕВЕ addr 


‚dictionary space on to the stack. 


-- H addr 


Attempts to find the word following the 
character in the dictionary. When found 


the address is placed on the stack. 


: addr 


If the word cannot be found, the ERROR U 


message will be displayed. U stands 
for Undefined word. 
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This places the memory location which 
contains the address of the next free 


PAD 


This places the address of a 64 byte 
scratch pad on the stack. The scratch 
pad can be used for storage by the user. 
The PAD will build into other sections 
of the TREE-FORTH language. Be 
careful not to overwrite this area. 


-- PAD addr 


56 


DATA 


w 


CHAPTER 10 


TYPES and VARIABLES 


E 


au 


19.1 DATA TYPES 


TREE-FORTH as you probably realize by 
now operates on either 16 bit integers or 32 
bit integers ( double precision ). There are 
operators for both types of numbers. Integers 
are one type of data. Another type are char- 
acters. TREE-FORTH characters are standard 
ASCII characters and can be found in APPENDIX 
A. On some systems, floating point numbers 
are included. Due to lack of space TREE 
SYSTEMS is not able to put floating point 


arithmetic in the TREE-FORTH EPROM without 
an extension. 


In this chapter, the different types of data 
variables are examined. | 


19.2 VARIABLE : This word gives a variable name 
a specific address in the 
dictionary and then defines 2 
bytes in the dictionary for 
values. Anytime that name is used 
in FORTH, the address of that 
variable is placed on the user 
stack. The variable can also be 
given an initial value. 


Definition : 
value VARIABLE varname 


Where : 
value = a numeric value to be 
assigned to the variable 


varname = a character name 


| chosen by the programmer. 
USAGE : 


After the initial definition any 
time the varname is used it places 


the address of the variable on the 
user stack. 


TYPICAL USAGE 


0 VARIABLE AVG (ENTER) 
initial name 
value 
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% 


1003 


Now enter : 
AVG . (ENTER) 


and the variable address will 
be displayed. 


The user can also use a 2VAR for double 
numbers. This command creates a 4 byte dic- 
tionary space for a 32 bit storage. Using 
the variable that 2VAR creates will put the 
address of the lst of the 4 bytes on the user 
Stack. 


INTEGER : 
This command is very much like 
variable. It creates a 2 byte 
variable in the dictionary, but 
instead of placing the address of 
the varaible on the stack, it 
Places the actual value. 


COMMAND : 
value INTEGER varname 


Where value is an initial value for 
the variable, 
Varname is the name associated 
with a specific address in memory. 
USAGE : 
@ INTEGER AVG 


initial name 
value 


The variable AVG, short for average, 
will be given an initial value of @ and 
defined in memory. | 


To store а new value at an INTEGER var- 
iable use the commands : 


val TO varname 
For example to store a value at AVG type : 


45 TO AVG (ENTER) 
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ARRAYS : 
Arrays can be created in FORTH 
just as in BASIC, FORTRAN, or 
other languages. 


First, space must be alloted in 
the dictionary. 


The commands are : 
9 VARIABLE VAL 20 ALLOT (ENTER) 


This will create a variable named VAL; then 
it gives VAL an initial value of 0, and puts 
20 bytes in the dictionary for the variable 
VAL. 

To access any 2 byte value in the array, 
Put the nth item on the stack and use the 
following commands. 


2* VAL + @ (ENTER) 


This will access the proper space by 
doubling the index and adding it to the 
address and fetching the proper address. 


This is not the only way to construct 
arrays. A more efficient and elegant way is 
to use the «BUILDS ... DOES» construct. This 
method will be shown in the chapter on 
defining words. 


Printer Commands : 

P toggles the printer on or off. If the printer 
routine is on, any information that goes to the video display will 
also go to the printer. As an example : 

To get a listing of all the FORTH words presently in the 
dictionary, type : 


P ( enter ) 
VLIST ( enter ) 
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CHAPTER 11 


CONTROL STRUCTURES 
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d» 


Note: Unlike other FORTH versions, TREE FORTH allows the 
user to use the ІР ... ELSE ... THEN and the ... DO ... LOOP 
Statements outside of a definition. That is, TREE FORTH allows 
you to generate header-less code. They can be entered 
interactively in the execution screen, 


CONDITIONAL STATEMENTS : 
11.1 IF ... ELSE ... THEN 


IE ... ELSE ... THEN : This is a special compiling set 
of words which can be used to make logical branches. 


IF 2 checks the top entry on the stack. If the top 
Stack entry is non-zero, the code between the IF and ELSE is 
executed. If the top entry is zero, the code between the ELSE 
and the THEN is executed. 


EXAMPLE OF USAGE : 


IF 
* This code is executed if the 
А top stack entry is non-zero. 
ELSE 
A This code is executed if the 
. top entry is zero. 
THEN 


Try the following commands on the exectution screen. 


(ЕМТЕВ) puts 1 on the stack 
IF 11+. ELSE 2 2 + . THEN (ENTER) 


| The statement between IF and ELSE will be exe- 
‘cuted. The screen should display the addition of 1 and 
Ls or 2 

2 OK 


Now try the following: 


g (ENTER) 
IF 1 1 +. ELSE 2 2 + . THEN (ENTER) 


The result: 4 OK. 
The statements between ELSE and THEN are executed. 
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11.2 


11.3 


-әегееФеегее ТНЕМ 


A simpler construct than the IF .. ELSE .. ТНЕМ is : 


IF ...... ө code ....... o THEN 


This statement allows the execution of code if the 


value on the stack is non-zero. 


An example is : 


1 (ENTER) 
IF 1 1 + . THEN (ENTER) 


This would display the addition of 1 + 1, or: 
2 OK 


If the initial stack entry were zero, then the 


code would not be executed. 


DO +... LOOP 


The structure of this statement is two indicies 


followed by executible code within the DO and LOOP 
words : 


limit initial. DO .... соае.... LOOP 


limit : the upper limit of the count for the 
loop 


initial : the low limit of the count for the 
loop. 


The indices are incremented from the initial 


value to the limit by one. The value of the count is 
stored in the variable I. 


An example : 
Type in the following. : 
9 d DO I . LOOP (ENTER) 
The following would be displayed. 
OF 1 2 3 4 5 € 7 8 ок 


Note that the upper limit, 9 in this case does 
get executed. This is the value to check against 


in the internal routine. ` 
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11.4 .... DO ... FLOOP 


This construct allows the user to increment or 
decrement the count by any value. 


This is the construction : 
limit initial DO statements increment +LOOP 


limit : is the upper or lower limit for the 
loop. 


initial : this is the value where the count is 
started. 


statements : any FORTH word. 


increment : any positive or negative value. 


Example : 
-5 0 DO Г . -1 +LOOP (ENTER) 


will display the following : 


0 -1 -2 -3 -4 ОК . 
% A very useful command for the DO LOOP construct is 
LEAVE 


Ж 


This terminates the loop at the next LOOP or 
+LOOP. It could be placed in an IF THEN clause. 


For nested loops a second index is available. The 
index is J. For further nested loops the NI index can 
be used. 

9 NI corresponds to I 

l NI corresponds to J 

2 NI would correspond to the next index. 

Li.5 CASE STATEMENT 


The case statement allows transfer to many places 
on the bases of an index. 


CASE is most often used in a definition, however 
it can also be used interactively on the execution 
" screen. 


The command format follwos: 
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11.6 


CASE el е2 ез e4 ... ; 


STACK VALUE EXECUTION PRIORITY 


SUMMARIZED : The statement at el is executed when 
the stack has a value of 9, e2 when the stack ' 
value is l, etc. 


el may be a FORTH definrton,. ог any 
mathematical expression. To test a CASE type; 


2 (ENTER) 
OK 

3 (ENTER) 
OK 

1 (ENTER) 
ок 


CASE * + ; (ENTER) 

OK ( this should execute 2 + 3 ) 
e (ENTER) 
5 ОК ( 5 will be the display ) 


BEGIN ..... AGAIN 


This statement will execute any code found between 
the BEGIN and AGAIN words. When AGAIN is reached, 
control is transferred to BEGIN and the code is exe- 
cuted. again. тіз creates ап infinite loop. 


Example : 
BEGIN ." HELLO " CR AGAIN (ENTER) 
This will print out : 


HELLO 
HELLO 
HELLO 
HELLO 


е 


А HELLO's will continue to be 
Printed to the bottom of the 
Screen, and then the print will 
continue by scrolling. 
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1152 


11.3 


BEGIN 


....... UNTIL 


This statement continues to execute the code 


found 


after BEGIN until the value on the top of stack 


matches the flag. 


Here is the construct : 
BEGIN statements logical operation UNTIL 


statements : this can be any group of FORTH 
words. 


logical operation : this leaves a true or false 
value on the stack which is 
interpreted by UNTIL . If the 
flag is true, non-zero, the 
loop is terminated, otherwise 
the execution is continued. 


Example : 
0 BEGIN 1% DUP DUP . 9 = UNTIL (ENTER) 


The above increments the top. of the stack by 
one. Then the value is duplicated twice in order 
to save the value before displaying it, and per- 
forms the logical operation. 


1 2 3 4 5 6 7 8 9 ок 


Notice that in this case the 9 is printed 
out. This is because the FORTH statements are 
executed before UNTIL checks the top value of the 
Stack against the flag. 


.BEGIN ... WHILE.... REPEAT 


BEGIN 


The construction of this word is as follows: 
BEGIN words logical operation WHILE words REPEAT 


words : this can be any FORTH word or combination 
of words. 


logical operation : this is a logical operator 
which leaves either a true or a false 
value on the stack. 

Example : 


1% DUP DUP . 5 > WHILE ." END" REPEAT (ENTER) 


The following will be displayed : 


@ 12 3 4 5 6 END OK 
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CHAPTER 12 


CHARACTER INPUT OUTPUT 
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12.1 


12.2 


CHARACTER STACK 


TREE-FORTH is unique in that it has both a number 
stack and a character stack. 


The character stack stores bytes of ASCII 
code. The stack pointer for the character stack can be 
found at address FC84 H. - The stack pointer for the 
number stack can be found in the IY register of the 
processor. These stacks are indepedent of each other. 
However, the character stack does keep track of how 
many characters are stored through a number which is 
placed on the top of the number stack. This explains 
why you might find an entry on the user stack which you 
did not place there. Also, the error routines will 
use the user stack as storage for information. 


CHARACTER COMMANDS к 
STRING 1/0 


." : Defines the beginning of a string of 
characters to be output to the screen. 


" : This can define the beginning of a 
string of characters to be put to the 
character stack. The length of the 
string is put on the number stack. The 
parser expects a space immediately after 
the initial " and does not count it as a 
character. 


"2; Defines the end of a string of charac- 
ters. 


Some examples : 
." THIS IS A STRING " 


When placed in a definition or in the 
execution screen will display the given 
string. ( The parser expects a space 
after ." ) | - 


" THIS IS A STRING " 


This will insert the given string in the 
character buffer with the number of 
characters on the number stack. ( The 
parser expects a space after the initial 
" , and does not count this as a charac- 
ter.) 
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EMIT 


KEY 


5@ 


.. 


ABORT" : 


A flag on the “user stack is 
checked, and if the flag is true 
(positive) then the user defined error 
message is displayed and a warm restart 
is executed. The user error message 
should appear after the initial quote 
mark, but it must be seperated by a 
space. Also, the -phrase should end 
with a double quote. This commad can be 
very useful for displaying user defined 
error messages in a program. 


CR : Defines a carriage return line feed 
on the screen. 

So, executing the following: 

5 8 DO ." THIS IS A STRING " CR LOOP (ENTER) 

would produce : 


count 


THIS IS A STRING ( 0 ) 
THIS IS A STRING ( count 1 ) 
THIS IS A STRING ( count 2 ) 
THIS IS A STRING ( count 3 ) 
THIS IS A STRING ( count 4 ) 
OK 


This is a command used to output a character to the 
console screen. EMIT looks for the ASCII number of a 
character on the user stack ( number stack ) and 
places the appropriate character оп the screen. 


This is a command which will get a value from the 
keyboard and put the ASCII equivalent of the key 
character on to the number stack. 


This command gets a word from the stack ( ending with a 
space or Carriage Return, CR,) and puts the wordon to 
the character stack. : 


This stores a string of characters found on the charac- 
ter stack to the address specified according to the 
length found on the number stack. 


addr М! ---- 
number of chars 


The number of characters is stored in the first byte of 
the string where it is stored in memory. 


69 


ма 


«С 


WDROP 


WDUP 


oe 


This will fetch a string of characters from the address 
specified. It places the characters on the character 
stack and the number of characters on the user number 
stack. 


addr WE  ------- 
number of characters. 


This allows output of a string to the Console screen, 
Editor screen, or any user defined screen. The command 
expects to find the string on the character stack with 
the number of characters on the user stack. It must be 
proceeded with a vaild screen identifier. 

Examples : 

On the execution screen enter the following : 

" THIS IS A STRING" (ENTER) 


To display this to the Console screen ( the execu- 
tion screen ) type : 


CO .W (ENTER) 
To display this to the editor screen type : 
ED .W (ENTER) 
To display the string to any other screen type : 
screen identifier .W (ENTER) 
This command OTIS the same format as .W. However, it 


places a character to the specified screen. 


This command word drops a word off the character stack. 
It assumes that the number of characters in the word is 
stored on the user stack. 


This command will duplicate the top word 
on the character stack. The number of characters in 
the word must be stored on the user stack. 
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12,3 


CON 


NOC 


># 


CHARACTER STACK / NUMBER STACK OPERATIONS 


There are a group of commands in TREE-FORTH which 
use both the number stack (or user stack) and the 
character stack. These commad types are described in 
this section. 


This command removes 1 character from the character 
stack and places the ASCII equivalent of that number on 
the user stack. 


This produces’ the oppisite effect of C>N. It takes a 
number off the user stack and attempts to convert it to 
an ASCII equivalent. If the conversion is successful 
the equivalent character is placed on the character 
stack ( in ASCII representation ). 


This command right-justifies the number of characters 
specified by the second stack entry, nl, in a field 
specified by the top stack entry. 


This will convert the characters on the the character 
string to a number. Therefore, if the character repre- 
sentation of 1002 is found on the character stack, then 
it will be converted to 199 on the user stack. This 
command expects to find the length of the character 
string on the number stack. 


This command leaves a flag on the user stack above the 
converted number which is a 1 if the conversion is 
successful, otherwise it is a 0. If the conversion is 
unsuccesful the character string will be left 
unchanged and can be used to prompt the user for 
a correct character string. 
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CHAPTER 13 


DEFINING WORDS 
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FORTH is different from all other languages in 
that it allows the user to define his/her own words. 
Thus, the user can completely customize a set of words 
which can be used in or be in any other program. 


This section explains how words are defined using 
FORTH. Ы 


The basic construct is : 
2 wordname ......... ; 


In TREE-FORTH wordname is compiled into the dic- 
tionary as a word with a specific operation as defined 
after wordname and before the semi-colon. 


Here is an example : 


: AVG + 2 / ; (ENTER) 
ок 


Successfully typing the above word will define a 
word which adds the top two stack entries and divides 
by two. In other words, AVG finds the average of two 
numbers. 


To execute this word type : 


2 4 AVG . (ENTER) 
3 ок 


The above statement will put 2 on the stack, then 
put 4 on the stack, then execute the commands attached 
to AVG, and finally display the top stack entry left by 
AVG. 


Next, we will define a word that takes the average 
of two sets of numbers by using AVG, and then check to 
see if the averages are equal. It will also print the 
appropriate response. 


: EQUAL AVG ROT ROT AVG = IF 
." EQUAL " ELSE ." NOT EQUAL " THEN ; 


The 2 ROT commands here are included to put the 


value calculated by AVG on the bottom of the stack and 
the next two numbers to be averaged on the top. 


$3 


% 


22.0... <BUILDS ... DOES? ..... 5 

This із one of the most important constructs іп 
FORTH yet it is the least understood. However, with 
a little careful study you should understand 1+. 


The formal command for this construct is : 


: defining word <BUILDS definition code DOES> 
run time code ; 


WHERE : 
defining word : this is a user specified word. 


definition code : this code is executed when the 
defining word is used to create a new word. 


run time code : this code is executed when the new 
word is used as a command word. 


NOTE : IT IS POSSIBLE TO HAVE NO DEFINITION CODE 
OR NO RUN TIME CODE. 


An example : 

: ARRAY «BUILDS 20 ALLOT DOES> ; 

Here is an example of <BUILDS ... DOES> construct 
with no run time code. This statement will allow the 
user to create arrays of 20 bytes. ( 20 ALLOT creates 
28 bytes in the dictionary ). ARRAY, then, becomes a 
word which will compile 28 bytes in the dictionary for 
any new word, 

ARRAY is used as follows : 

ARRAY NUMBER (ENTER) 


This creates an array called NUMBER and this array 
will have 29 bytes attached to it in the dictionary. 


To access these 20 bytes we want to put the 
address where they are found onto the stack. This is 
done any time NUMBER is used. So, typing : 

NUMBER (ENTER) 


This command places the address of the first byte 
of the 28 bytes alloted to NUMBER on to the stack 
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The program can be expanded as shown below. We will 
create a 1 dimensional array and allow the user to 
access any number in the array by placing an index on 
the stack. 


: ARRAY1 «BUILDS 40 ALLOT DOES> SWAP 2* +; 


ARRAY1 will build a 40 byte, 20 word array. To 
do that : 


ARRAY1 XYZ (ENTER) 


Now, in the dictionary, we have created an array 
called XYZ. 


Next, we will insert a number, say 01, into the 
llth word in this array. gue 


01 11 XYZ ! (ENTER) 
What has happened up to this point ? 


First, a 01 was placed on the number stack. 
Secondly, the index of 11 was placed on the stack. Then 
XYZ is encountered.It first places the address in the 
dictionary where the array is located and then 
initiates the execution of the code following DOES». 
In this case the top two entries on the stack are 
swapped (putting the index on the top and the address 
below it). Next the index is doubled by 2* because we 
are dealing with 16 bit values. Then it is added to the 
address. The stack now contains the address and the 
value, and a store (!) will put the value at the 
specified address. 


Another routine could be written to fetch values 
from the address. It would be : 


11 ХҮ2 8 (ENTER) 


(] : This word is used to suppress the execution of an 
immediate keyword іп a definition. The token which 
follows [_] will, if in a definition, be compiled to 
execute when the word being defined is executed and not 
during the definition of the word itself. 


E) : Note. any words placed in parenthesis will not be 
compiled and act as comments in your program. 
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FORGET 


* P 


FENCE 


You can forget any word in the dictionary with FORGET 
if it is not protected by the FENCE value, Simply 
type. 


FORGET word (ENTER) 


and ( word ) along with any dictionary entries compiled 
after ( word ) will be removed from the dictionary. 


You can protect any word from FORGET by typing 


FENCE word (ENTER) 
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CHAPTER 14 


TASKING 


77 


TREE-FORTH is very unique in that it allows the 
user to task. Tasking is the act of scheduling a 
program at some date in the future, Any program can be 
scheduled in a task. The tasking commands are given 
below in the order of use in defining tasks to run. 


NOTE: In TREE-FORTH you can run approximately 19 
tasks simultaneously in the background before the 
system will slow down so much as to be useless in 


editing new programs. ( Tasks use valuable processor 
time which is usually spent in editing new programs ). 


Tasking Format : 


TASK programname taskname 


where programname is any program which is defined 
in the dictionary by the user. 


taskname becomes the name associated with this 
task. 


Note that at this time the task has not yet been 
Scheduled to run, it has only been defined. 


SCHEDULING TASKS : 


The user can schedule a task to run using the IN, 
EVERY, AT commands. The time used can be : 


TT Task ticks ( 1/60th sec ) 
TS Task seconds 

TM Task minutes 

TH . Task Hours 

TD . Task Days 

TW Task weeks 

TY Task years 


The format for Scheduling is : 


command number time-type  taskname 


Example : 
EVERY 5 ТТ TASK1 


This schedules the task TASKI to run every 5 task 
ticks. í 


IN 1@ TM TASK1 


78 


This schedules the task ТА5КІ to run іп 19 
minutes. So, now the task is scheduled to run in 19 
minutes every 5 Task ticks. The system will 
automatically start scheduling this task upon the 
execution of this command. 


To terminate the execution of a task the STOP 
command can be used. The form of this command is: 


STOP taskname (ENTER) 
To restart a task you must reschedule it. 


Tasks may also be forgotten just as any other 
FORTH word. This is possible because every tasks is a 
component in the dictionary. So alternately, 


FORGET taskname (ENTER) 


Of course the task cannot be rescheduled after 
this command because it no longer exists in the 
dictionary. 

TREE-FORTH also allows for running a task with- 
out scheduling that task. This would be very helpful 
in debugging a task to insure that it is running 
properly. The command is : 


RUN taskname (ENTER) 


The next command to analyze is START, but this 
needs some background information. 


What should happen if your task was extremely 
long? That is, the task took much longer to run than 
1/60th of a second (the time to the next task update ). 
The task might be scheduled to run every 1/68th of a 
Second. In this case, the task would be rescheduled 
before it was completed. 


TREE-FORTH allows for this to happen. However, if 
your task were so slow that it continually rescheduled 
tasks before the previous one was finished the System 
would finally lock up. A single task can be "back 
scheduled" 63 times before the system will lock up. 
This is all more fully explained in the technical 
reference manual in Appendix C at the end of this book. 


Now back to START. START clears the task register 


of "back scheduled" tasks. This is done for one task 
at a time. The command format is: 
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LOCK 


UNLOCK 


TOFF 


TON 


START taskname (ENTER) 
Finally, two more task commands. 


prevents all tasks from running. Tasks are still being 
scheduled to execute during a LOCK condition but 
whatever program is being executed when lock is 
executed will gain second to highest priority in the 
system ( second only to the master 1/4 seccond task ) 
and will not be interupted by any other task. 


allows tasks which have been LOCKED out to begin 
executing again. 


LOCK should be run only for a short period of 
time. This command locks all tasks from running. 
If a task were longer than one interrupt cycle (1/60th 
of a second ) then the task would be qued-up. LOCK 
does not stop the scheduling of tasks to be run. It 
only stops their actual execution. Therefore, the 
possibility exists for a task to completely fill it's 
que buffer ( 63 scheduled executions ). Upon UNLOCKing 
the tasks, the task with the overflowed que would be 
blocked from running and could only be released by a 
START taskname. 


This command resets a flag so that upon the exechtion 
of a WARM restart the following items occur : 


- Causes a LOCK of all tasks 

- Resets the editor to the console 

- Sets the background task to a null task. 
- Forces display to SLOW mode. 


Disables TOFF and allows scheduled tasks to execute 
after a WARM restart. 
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CHAPTER 15 


CODE COMPILER 
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қ This section describes how machine code can be compiled. 
The advantages of writing in machine code are a decreased memory 
space used and increased execution speeds. 

ы Machine code is а term refering to the type of numbers the 
280 microprocessor inside the SINCLAIR will recognize. In real- 
ity it will only recognize combinations of 0"5 and l's; However, 
it is easier if we deal in the HEXADECIMAL representation of 
those numbers. Now, of course, it would be impossible to  remem- 
ber what every HEX number did inside of the 280 microprocessor. 
Therefore, each command is represented by a nmemonic, or a sym- 
bol. It is common practice to write source code in these nme- 
monics and then convert the nmemonic to the proper HEX number. 
TREE SYSTEMS has made a special arrangement will the ZILOG 
corporation ( the manufacturers of the 280 microprocessor ) to 
include a Programming Reference Guide with the documentation for 
TREE-FORTH. This will give you a simple source for the machine 

code conversions. 

! First, the CODE compiler will be described, and 
then an example of its use will be given. 


The CODE compiler has the following form : 
: word CODE ...... hex code i22. $C 3 


The above shows the CODE compiler in a definition. 
It could also be used outside of a colon definition 
alone in which case, it would place code at the pre- 
sent point in the dictionary. The definition, as 
shown, could be expanded to having any amount of TREE- 
FORTH words before CODE or after ;C. 


Here is an example : 


A machine code routine can be written to add the 
three numbers found on the user stack and put the 
result on the stack. We will use the HL and DE reg- 

` isters for this. i 


First a little background. TREE-FORTH supports 
commands for putting numbers on the stack and removing 
numbers fron the user stack. To remove a number from 
the stack the command is . | 


UPOP 
This command takes the number off the user stack 
and pops it into the HL register. The command is 
located at RST 2 and the HEX machine code is a 07. 
TO take a number from from the HL register and 


load it to the user stack the command is 
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UPUSH. 


UPUSH is located at RST 1 and the HEX machine code 
is СЕ. 


Now let's write the routine. The comments to the 
right of the semi-colon describe the logical order of 
events. 


ES PUSH HL ; This saves the contents of the HL 
DS PUSH DE ; and DE by placing them on the 
; processor stack. 

takes the top stack entry and 
; puts it in HL 
EB EX DE,HL ; this exchanges the contents of 
the HL and DE registers 

takes the 2nd stack entry and 
places in the HL register 

this adds the contents of HL and 
puts the result in HL. 

move answer of first addition 

to DE 

gets the third number 

Adds the third number with the 
sum of the first two. 

puts the final result back on 
‘the user stack. 


D7 UPOP 


we 


D7 UPOP 
19 ADD HL,DE 
EB EX DE,HL 


07 UPOP 
19 ADD HL,DE 


СЕ UPUSH 


D1 POP DE 
El POP HL 


wo vo чо чо %0 MO чо ve LA чо чо чо чо WE 


Restores the HL and DE registers 


No return is necessary; it is automatically 
inserted by ;C. 


Normally, the code would be compiled directly to 
the left of the above code after writing the entire 
program. Here, they are included side by side. 

Now, to enter this code in the dictionary under 
the command word 3+ the correct programming statement 
would be : 

: 3+ CODE ES 05 07 ЕВ 07 19 ЕВ 07 19 CE EL Di ;C ; 


To execute this word, place 3 numbers on the stack 
and use the new command. 


1 2 3 3% . (ENTER) 


3+ adds the three numbers and outputs the sum, 6, 
on the stack. '.' prints the top stack entry. 
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CHAPTER 16 
APPLICATIONS 


programs 
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One of the first programs you will want to try on TREE- 
. FORTH 15 a task which will continually display the user stack on 
the bottom of the console screen. The commands are given below. 


а The entire program should be typed on the editor screen. 
Then switch to the console screen and type CPL to compile the 
entire editor screen. 


-- top of editor -- HEX CLS 16 CO 5 + c! 
0 17 1F 17 SCREEN ST ST БЕУ 
$ SCL Ø C NOC ST W: 
:5Т0% 5 w^ ST NWN ; 
: ST4 4 04 DO 4 I - PICK STD LOOP 
, 
: STE SCL 5Т4 FA7E Spa - 2/ " 5 
Т = " ST .W STD ; 
TASK STK STE EVERY 2 TS STK 


Summary : The first line clears the console screen. The 
second line creates the reverse video display line at the bottom 
of the screen. The screen name is ST ( for stack screen ). The 
SCL word is a screen clear command. STD is a screen display 
command. Finally, ST4 is the word which displays the top 4 stack 
values. STE, stands for Stack Execute. This is the execution 
portion of the code. The routine clears the screen (SCL), then 
displays the top 4 entries (ST4), then gets the stack pointer 
value and displays that value to the stack screen (ST). Finally 
the last statement is a task which schedules the program called 
STE as a task called STK. The task is scheduled to run every 2 
seconds. 


Another little routine you may want to use is the 
following. This does the same thing as a READ 
statement in BASIC. 

: READ ." INPUT REQUEST " 58; 


This gets a string from the keyboard and places it 
on the character stack. To display the result type : 


CO .W (ENTER) 


Here is a little program to convert Fahrenheit degrees to 
Celcius degrees. 


First let us read in a variable : 


* : READ ."? " S@ ; 
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This will display a prompt ( ? ) and get a word 
from the user. 


Next we can write the word to convert the input to 
a number. 


> INPUT READ ># DROP ; 


># converts the top of the character stack to a 
number. We must drop a character because the 
conversion leaves a 1 or a 0 depending on whether or 
not the conversion is successful. 


Next let us write the actual conversion calculation. 
2 CEL 32 - 100 * 9 / S % 1900 / 5 
Note that the value must be scaled by 100 before performing 


the division. A later dividision by 100 is needed to bring the 
result back to its orginal scale. 


Next, we will write a routine which will giveusa 
printout in a nice format. 


: PRINT ." CELCIUS DEGREES " . ; 


Finally, here is the program word which ties all 
the others together : 


: CELC INPUT CEL PRINT ; 


Note that we could also test each word 
individually by typing each definition ( making sure 
that there is an appropriate value on the stack ). 


ANOTHER PROGRAM : 


HERE IS A PROGRAM TO CALCULATE STRAIGHT-LINE 
DEPRECIATION. 


We will modify the read statement from last time : 


: READ2 ." ? " 58 ># DROP ; 
0 VARIABLE AMT 

9 VARIABLE YEARS 

@ VARIALBE LAND 


Now that we have the variable names let us continue 
with the input statements : 


INA ." ENTER THE PURCHASE VALUE " READ AMT ! ; 
[МУ ." ENTER THE NUMBER OF YEARS " READ YEARS ! ; 
INL ." ENTER LAND VALUE " READ LAND ! : 
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Now the land value will be subtracted from the 
property value and the difference will be divided by 
the number of years to find the depreciation. 


: ОБР AMT 8 LAND 8 - 100 * YEARS 8 / 190 / ; 


Now let us print the result and arrange all the 
words into one command word. 


: PRINT ." STRAIGHT LINE DEPRECIATION : " . 
: PRODEP INA INY INL DEP PRINT ; 


LII 


After editing and compiling this program, you can 
execute it by typing PRODEP. 
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APPENDIX А 
ASCII CONVERSION TABLE IN HEX AND DECIMAL 


Note that the following listing includes all of 
the ASCII characters and their number equivalent. The 
SINCLAIR 2Х81 / TS 1000 in the FORTH mode will support 
all of the ASCII characters excluding lower case. 
Because TREE-FORTH completely replaces the basic ROM 
operating system all of the characters have been 
redefined to the exclusion of all graphics characters, 
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DECIMAL 


ASCII 


CHAR 


NUL 
SOH 


CHARACTER SET 
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HEX 


DECIMAL 


CHAR 


+ koam m 


AG n O0 n t0) ОС U » G 9) v I Ave о шола Л d CO ку кә Ge 


› н чм р 5 < сн о шю номе 


4 


SUL e. TO md ОСО со 


99 


b-———N'SXx£Stuü0rtuUurnrta'sooas8sgrmuve 


DEL 


APPENDIX B 


ERROR CODES 
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ERROR 


ERROR 


ERROR 


ERROR 


ERROR 


ERROR 


The following is a listing of error codes. These 
will appear in the form: 


ERROR letter 


An error will appear every time the user makes a 
mistake in writing or executing code. 


This error message is displayed when the user 
attempts to forget a fenced word. If the fenced word 
appears anywhere in the list of words being forgotten 
this error is displayed. 


This error message will be flagged if the user 
forgets to input a hexadecimal number in the code 
compiler. | 


This error message is displayed when the 
available usable memory ( RAM ) is almost full. This 
will occur when the user stack area runs to 
within .32 bytes of the dictionary space. 


Error R stands for redundant. If the user trys to 
define a word with a name which belongs to a program 
which already exists in the dictionary, the word is 
Still defined and will have priority over the previous 
word in the dictionary. 


This message is displayed if the stack underflows. 
That is, the error is flagged if the user attempts to 
take a value off the stack when the stack is empty. 


Error U stands for Undefined Word. This message 


is displayed when a word is used which has not been 
previously defined in the dictionary. 


92 


APPENDIX C 


TECHNICAL REFERENCE 


The technical reference is in progress 
and will be sent on request. 
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INDEX 


Items are arranged in alphabetical order by groups. 


ARITHMETIC ASCII EQUIVALENCE 
SINGLE PRECISION SEE APPENDIX A 
page 
+ 36 CHARACTER INPUT 
+- 39 : 
- 34 KEY 69 
* 37 se 69 
/ 37 
/мор 39 CHARACTER OUTPUT 
MOD 39 
* /MOD 40 EMIT 69 
M* 39 е 68 
M/ 40 " 68 
1+ 37 CR 74 
1- 37 eW 78 
2+ 38 ac 79 
2- 38 
2* 38 CHARACTER <--> + 
2/ 38 
ABS 38 CON 71 
MINUS 39 N»C 71 
ж 41 “> 71 
>% 71 
DOUBLE PRECISION | 
COMPARISONS 
D+ 41 
D+- 41 SINGLE PRECISION 
D- 41 
DABS 41 = 45 
DMINUS 42 < 44 
MD* 42 > 44 
MD/ 46 U< 46 
g= 45 
UNSIGNED д> 45 
g< 45 
U* 42 MIN 39 
UMOD 42 MAX 38 
U/MOD 42 А 
COMPARISONS DICTIONARY MANAGEMENT 
DOUBLE PRECISION ALLOT 52 
! БЕМСЕ 76 
D< 45 FORGET 76 
D> 45 HERE 55 
= 45 H 55 
Dg= 46 
DMAX 46 
DMIN 46 
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EDITOR COMMANDS 


SHIFT/EDIT 29 
COMPILATION <- 29 
20 
2 55 X 20 
С 55 -> 29 
CODE 88 SHIFT/9 20 
;C 82 SHIFT/4 20 
' 55 SHIFT/DELETE 20 
«BUILDS 74 SHIFT/3 21 
DOES» 74 SHIFT/2 21 
IMM C SHIFT/Q 23 
IN 78 CPL 23 
AT к 78 EOFF 23 
EVERY 78 
CON 29 LOGICAL OPERATORS 
COFF 29 
[ 75 AND 44 
] 75 OR 44 
( 75 XOR 44 
) 75 


MEMORY OPERATIONS 
DEFINING WORDS | 


@ 52 
$ 13 ! 52 
; 73 ? 52 
+1 52 
+ORG 54 
INTEGER 59 | с! 54 
TASK 78 са 54 
SCREEN 25 BLK 54 
VARIABLE 58 COPY 54 
DG 55 
D! .54 
MEMORY COMMANDS STACK MANIPULATION 
( continued ) 
2DROP 49 
FBUF 54 DROP 49 
FILL 56 DUP 49 
PAD 56 ?DUP 49 
5Р@ 52 DSWAP 49 
ма 78 OVER 54 
И! 69 PICK 49 
| SWAP 49 
| ROT 50 
NUMERIC OPERATORS WDROP 7@ 
WDUP 7@ 
BASE 48 # C 
DECIMAL 48 | оф Li © 
НЕХ 48 - D# C 
S->D 49 A>H G 
D-»Q 49 | H>A c 
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NUMBER OUTPUT 


oO 
° . 


OPERATING SYSTEM 


ABORT" 
AUTO 


CONTORL STRUCTURES 


BEGIN .. AGAIN 
BEGIN .. UNTIL 
BEGIN .. WHILE 


-. REPEAT 


DO .. LOOP 
DO .. +LOOP 
ТЕ as ELSE ., 

ee THEN 
IF .. THEN 


TY 
TOFF 
TON 
UNLOCK 
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